home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / C / Applications / MacPerl 5.0.3 / MacPerl Source ƒ / MacPerl5 / pod / modpods / GetOptions.pod < prev    next >
Encoding:
Text File  |  1994-12-26  |  4.1 KB  |  138 lines  |  [TEXT/MPS ]
  1. =head1 NAME
  2.  
  3. Getopt::Long, GetOptions - extended getopt processing
  4.  
  5. =head1 SYNOPSIS
  6.  
  7.     use Getopt::Long;
  8.     $result = GetOptions (...option-descriptions...);
  9.  
  10. =head1 DESCRIPTION
  11.  
  12. This package implements an extended getopt function. This function adheres
  13. to the new syntax (long option names, no bundling).
  14. It tries to implement the better functionality of traditional, GNU and
  15. POSIX getopt() functions.
  16.  
  17. Each description should designate a valid Perl identifier, optionally
  18. followed by an argument specifier.
  19.  
  20. Values for argument specifiers are:
  21.  
  22.   <none>   option does not take an argument
  23.   !        option does not take an argument and may be negated
  24.   =s :s    option takes a mandatory (=) or optional (:) string argument
  25.   =i :i    option takes a mandatory (=) or optional (:) integer argument
  26.   =f :f    option takes a mandatory (=) or optional (:) real number argument
  27.  
  28. If option "name" is set, it will cause the Perl variable $opt_name to
  29. be set to the specified value. The calling program can use this
  30. variable to detect whether the option has been set. Options that do
  31. not take an argument will be set to 1 (one).
  32.  
  33. Options that take an optional argument will be defined, but set to ''
  34. if no actual argument has been supplied.
  35.  
  36. If an "@" sign is appended to the argument specifier, the option is
  37. treated as an array.  Value(s) are not set, but pushed into array
  38. @opt_name.
  39.  
  40. Options that do not take a value may have an "!" argument spacifier to
  41. indicate that they may be negated. E.g. "foo!" will allow B<-foo> (which
  42. sets $opt_foo to 1) and B<-nofoo> (which will set $opt_foo to 0).
  43.  
  44. The option name may actually be a list of option names, separated by
  45. '|'s, e.g. B<"foo|bar|blech=s". In this example, options 'bar' and
  46. 'blech' will set $opt_foo instead.
  47.  
  48. Option names may be abbreviated to uniqueness, depending on
  49. configuration variable $autoabbrev.
  50.  
  51. Dashes in option names are allowed (e.g. pcc-struct-return) and will
  52. be translated to underscores in the corresponding Perl variable (e.g.
  53. $opt_pcc_struct_return).  Note that a lone dash "-" is considered an
  54. option, corresponding Perl identifier is $opt_ .
  55.  
  56. A double dash "--" signals end of the options list.
  57.  
  58. If the first option of the list consists of non-alphanumeric
  59. characters only, it is interpreted as a generic option starter.
  60. Everything starting with one of the characters from the starter will
  61. be considered an option.
  62.  
  63. The default values for the option starters are "-" (traditional), "--"
  64. (POSIX) and "+" (GNU, being phased out).
  65.  
  66. Options that start with "--" may have an argument appended, separated
  67. with an "=", e.g. "--foo=bar".
  68.  
  69. If configuration varaible $getopt_compat is set to a non-zero value,
  70. options that start with "+" may also include their arguments,
  71. e.g. "+foo=bar".
  72.  
  73. A return status of 0 (false) indicates that the function detected
  74. one or more errors.
  75.  
  76. =head1 EXAMPLES
  77.  
  78. If option "one:i" (i.e. takes an optional integer argument), then
  79. the following situations are handled:
  80.  
  81.    -one -two        -> $opt_one = '', -two is next option
  82.    -one -2        -> $opt_one = -2
  83.  
  84. Also, assume "foo=s" and "bar:s" :
  85.  
  86.    -bar -xxx        -> $opt_bar = '', '-xxx' is next option
  87.    -foo -bar        -> $opt_foo = '-bar'
  88.    -foo --        -> $opt_foo = '--'
  89.  
  90. In GNU or POSIX format, option names and values can be combined:
  91.  
  92.    +foo=blech        -> $opt_foo = 'blech'
  93.    --bar=        -> $opt_bar = ''
  94.    --bar=--        -> $opt_bar = '--'
  95.  
  96. =over 12
  97.  
  98. =item $autoabbrev      
  99.  
  100. Allow option names to be abbreviated to uniqueness.
  101. Default is 1 unless environment variable
  102. POSIXLY_CORRECT has been set.
  103.  
  104. =item $getopt_compat   
  105.  
  106. Allow '+' to start options.
  107. Default is 1 unless environment variable
  108. POSIXLY_CORRECT has been set.
  109.  
  110. =item $option_start    
  111.  
  112. Regexp with option starters.
  113. Default is (--|-) if environment variable
  114. POSIXLY_CORRECT has been set, (--|-|\+) otherwise.
  115.  
  116. =item $order           
  117.  
  118. Whether non-options are allowed to be mixed with
  119. options.
  120. Default is $REQUIRE_ORDER if environment variable
  121. POSIXLY_CORRECT has been set, $PERMUTE otherwise.
  122.  
  123. =item $ignorecase      
  124.  
  125. Ignore case when matching options. Default is 1.
  126.  
  127. =item $debug           
  128.  
  129. Enable debugging output. Default is 0.
  130.  
  131. =back
  132.  
  133. =head1 NOTE
  134.  
  135. Does not yet use the Exporter--or even packages!!
  136. Thus, it's not a real module.
  137.  
  138.